---
title: Lua Reference - kong.tools.responses
layout: default
---


<header class="page-header">
  <div class="container">
    <div class="page-header-icon">
      <img src="/assets/images/icons/icn-documentation.svg" alt="Documentation" />
    </div>
    <div class="page-header-title">
      <h1>Public Lua API Reference</h1>
      <p>For plugins developers and core contributors</p>
    </div>
    {% if site.data.kong_versions.size > 1 %}
      {% include lua-reference-dropdown.html
        page=page
        site=site
      %}
    {% endif %}
  </div>
</header>

<div class="container">
  <aside class="page-navigation">
    <nav>
      <ul>
        <li>
          <a href="/{{page.kong_version}}"><h5>Back to docs</h5></a>
        </li>
        <li>
          <a href="/{{page.kong_version}}/lua-reference/"><h5>Index</h5></a>
        </li>
        <li>
          <h5>Modules</h5>
          <ul>
            <li><a href="../../modules/kong.dao.cassandra.base_dao">kong.dao.cassandra.base_dao</a></li>
            <li><a href="../../modules/kong.kong">kong.kong</a></li>
            <li><a href="../../modules/kong.plugins.basic-auth.crypto">kong.plugins.basic-auth.crypto</a></li>
            <li><a href="../../modules/kong.plugins.jwt.jwt_parser">kong.plugins.jwt.jwt_parser</a></li>
            <li><a href="../../modules/kong.plugins.log-serializers.alf">kong.plugins.log-serializers.alf</a></li>
            <li><a href="../../modules/kong.tools.io">kong.tools.io</a></li>
            <li>kong.tools.responses</li>
            <li><a href="../../modules/kong.tools.timestamp">kong.tools.timestamp</a></li>
            <li><a href="../../modules/kong.tools.utils">kong.tools.utils</a></li>
          </ul>
        </li>
      </ul>
    </nav>
  </aside>

  <div class="page-content-container">
  <div class="page-content">
    <div class="content">
<h1><code>kong.tools.responses</code></h1>
<p>Kong helper methods to send HTTP responses to clients.</p>
<p><p> Can be used in the proxy (core/resolver), plugins or Admin API.
 Most used HTTP status codes and responses are implemented as helper methods.</p>


<pre>
<span class="keyword">local</span> responses = <span class="global">require</span> <span class="string">"kong.tools.responses"</span>

<span class="comment">-- In an Admin API endpoint handler, or in one of the plugins' phases.
</span><span class="comment">-- the <code>return</code> keyword is optional since the execution will be stopped
</span><span class="comment">-- anyways. It simply improves code readability.
</span><span class="keyword">return</span> responses.send_HTTP_OK()

<span class="comment">-- Or:
</span><span class="keyword">return</span> responses.send_HTTP_NOT_FOUND(<span class="string">"No entity for given id"</span>)

<span class="comment">-- Raw send() helper:
</span><span class="keyword">return</span> responses.send(<span class="number">418</span>, <span class="string">"This is a teapot"</span>)
</pre></p>



<h2><a href="#Functions">Functions</a></h2>
<table class="function_list">
  <tr>
    <td class="name"><a href="#send">send (status_code, body, raw, headers)</a></td>
    <td class="summary">Send a response with any status code or body,
 Not all status codes are available as sugar methods, this function can be
 used to send any response.</td>
  </tr>
</table>
<h2><a href="#Tables">Tables</a></h2>
<table class="function_list">
  <tr>
    <td class="name"><a href="#status_codes">status_codes</a></td>
    <td class="summary">Define the most common HTTP status codes for sugar methods.</td>
  </tr>
</table>


<h2 class="section-header "><a name="Functions">Functions</a></h2>


<dl class="function">
  <hr />
  <dt>
    <h4><a name="send">send</a></h4>
  </dt>
  <dd>
    Send a response with any status code or body,
 Not all status codes are available as sugar methods, this function can be
 used to send any response.
 If the <code>status_code</code> parameter is in the 5xx range, it is expectde that the <code>content</code> parameter be the error encountered. It will be logged and the response body will be empty. The user will just receive a 500 status code.
 Will call <a href="https://github.com/openresty/lua-nginx-module#ngxsay">ngx.say</a> and <a href="https://github.com/openresty/lua-nginx-module#ngxexit">ngx.exit</a>, terminating the current context.

    <h5>Parameters:</h5>
    <ul>
        <li>
          <code class="parameter">status_code</code>
          <span class="types"><span class="type">number</span></span>
          HTTP status code to send
        </li>
        <li>
          <code class="parameter">body</code>
          A string or table which will be the body of the sent response. If table, the response will be encoded as a JSON object. If string, the response will be a JSON object and the string will be contained in the <code>message</code> property. Except if the <code>raw</code> parameter is set to <code>true</code>.
        </li>
        <li>
          <code class="parameter">raw</code>
          <span class="types"><span class="type">boolean</span></span>
          If true, send the <code>body</code> as it is.
        </li>
        <li>
          <code class="parameter">headers</code>
          <span class="types"><a class="type" href="http://www.lua.org/manual/5.1/manual.html#5.5">table</a></span>
          Response headers to send.
        </li>
    </ul>

    <h5>Returns:</h5>
    <ul>
      <li>
        ngx.exit (Exit current context)
      </li>
    </ul>


    <h5>See also:</h5>
    <ul>
      <li><a href="https://github.com/openresty/lua-nginx-module#ngxsay">ngx.say</a></li>
      <li><a href="https://github.com/openresty/lua-nginx-module#ngxexit">ngx.exit</a></li>
    </ul>



  </dd>
</dl>

<h2 class="section-header "><a name="Tables">Tables</a></h2>


<dl class="function">
  <hr />
  <dt>
    <h4><a name="status_codes">status_codes</a></h4>
  </dt>
  <dd>
    Define the most common HTTP status codes for sugar methods.
 Each of those status will generate a helper method (sugar)
 attached to this exported module prefixed with <code>send_</code>.
 Final signature of those methods will be <code>send_&lt;status_code_key&gt;(message, raw, headers)</code>. See <a href="send">send</a> for more details on those parameters.

    <h5>Fields:</h5>
    <ul>
        <li>
          <code class="parameter">HTTP_OK</code>
          200 OK
        </li>
        <li>
          <code class="parameter">HTTP_CREATED</code>
          201 Created
        </li>
        <li>
          <code class="parameter">HTTP_NO_CONTENT</code>
          204 No Content
        </li>
        <li>
          <code class="parameter">HTTP_BAD_REQUEST</code>
          400 Bad Request
        </li>
        <li>
          <code class="parameter">HTTP_UNAUTHORIZED</code>
          401 Unauthorized
        </li>
        <li>
          <code class="parameter">HTTP_FORBIDDEN</code>
          403 Forbidden
        </li>
        <li>
          <code class="parameter">HTTP_NOT_FOUND</code>
          404 Not Found
        </li>
        <li>
          <code class="parameter">HTTP_METHOD_NOT_ALLOWED</code>
          405 Method Not Allowed
        </li>
        <li>
          <code class="parameter">HTTP_CONFLICT</code>
          409 Conflict
        </li>
        <li>
          <code class="parameter">HTTP_UNSUPPORTED_MEDIA_TYPE</code>
          415 Unsupported Media Type
        </li>
        <li>
          <code class="parameter">HTTP_INTERNAL_SERVER_ERROR</code>
          Internal Server Error
        </li>
    </ul>




    <h5>Usage:</h5>
    <ul>
      <li><pre class="example"><span class="keyword">return</span> responses.send_HTTP_OK()</pre></li>
      <li><pre class="example"><span class="keyword">return</span> responses.HTTP_CREATED(<span class="string">"Entity created"</span>)</pre></li>
      <li><pre class="example"><span class="keyword">return</span> responses.HTTP_INTERNAL_SERVER_ERROR()</pre></li>
    </ul>


  </dd>
</dl>


    </div>
  </div>
</div>
</div>
